#%RAML 0.8
---
title: Builder Admin API
version: v1

baseUri: https://{rootUri}/{version}
baseUriParameters:
    rootUri:
        description: |
            The root URI for the particular installation of Builder
        example: admin.habitat.sh, localhost:8080

mediaType: application/json
schemas:
    - account: |
        {
            "properties": {
                "id": {
                    "type": "string",
                    "required": true
                },
                "email": {
                    "type": "string",
                    "required": true
                },
                "name": {
                    "type": "string",
                    "required": true
                }
            }
        }
    - searchTerm: |
        {
            "properties": {
                "entity": {
                    "enum": ["account"],
                    "required": true
                },
                "attr": {
                    "enum": ["id", "name"],
                    "required": true
                },
                "value": {
                    "type": "string",
                    "required": true
                }
            }
        }
securitySchemes:
    - oauth_2_0:
        description: Builder supports OAuth 2.0 for authenticating all API requests.
        type: OAuth 2.0
        describedBy:
            headers:
                Authorization: &authorization
                    description: Used to send a valid OAuth 2 access token.
                    example: |
                        Authorization: Bearer 0b79bab50daca910b000d4f1a2b675d604257e42
            responses:
                401: &resp401
                    description: |
                        Bad or expired token. To fix, you should re-authenticate the user.
                403: &resp403
                    description: |
                        Bad OAuth request. Regenerate your token and try again.
        settings:
            authorizationUri: https://{rootUri}/oauth2/authorize
            accessTokenUri: https://{rootUri}/oauth2/token
            authorizationGrants: [ token ]

/status:
    get:
        description: Returns the health of the service
        responses:
            200:
                description: Service is healthy
            500:
                description: Server fault
            503:
                description: Service temporarily unavailable
/authenticate/{code}:
    get:
        responses:
            200:
                body:
                    application/json:
                        example: |
                            {
                                "token": "0b79bab50daca910b000d4f1a2b675d604257e42",
                                "email": "reset@chef.io",
                                "name": "reset",
                                "id": 73089155726360582
                            }
/search:
    post:
        description: |
            Search an entity collection for entities matching the given search term
        securedBy: [oauth_2_0]
        body:
            application/json:
                schema: searchTerm
                example: |
                    {
                        "entity": "account",
                        "attr": "email",
                        "value": "reset@chef.io"
                    }
        responses:
            200:
                description: One or more matching entities found
            404:
                description: No matching entities found
            422:
                description: Malformed search term in request body
/accounts:
    /{id}:
        get:
            description: Return an account entity matching the given ID
            securedBy: [oauth_2_0]
            responses:
                200:
                    body:
                        application/json:
                            schema: account
                            example: |
                                {
                                    "email": "reset@chef.io",
                                    "id": "42123940398628864",
                                    "name": "reset"
                                }
/features:
    get:
        description: List all features
        securedBy: [oauth_2_0]
        responses:
            200:
                body:
                    application/json:
                        example: |
                            [
                                {
                                    "name": "Admin",
                                    "id": 1
                                },
                                {
                                    "name": "Builder",
                                    "id": 2
                                }
                            ]
    /{id}:
        /teams:
            get:
                description: List of GitHub teams granted the feature flag
                securedBy: [oauth_2_0]
                responses:
                    200:
                        body:
                            application/json:
                                example: |
                                    [
                                        2081220,
                                        2059358
                                    ]
                    404:
                        description: No feature flag found matching id
            post:
                description: Grant a GitHub Team the feature flag
                securedBy: [oauth_2_0]
                body:
                    application/json:
                        example: |
                            {
                                "team_id": 2081220
                            }
                responses:
                    204:
                        description: Feature flag successfully granted to GitHub team
            /{id}:
                delete:
                    description: Revoke the feature flag from the GitHub Team
                    responses:
                        204:
                            description: Feature flag successfully revoked from GitHub team
